SPACE 2/SPACE - Library 2 - Volume 1.iso/program/318/utilsrc/make-3

Text File | 1988-10-20 | 48.2 KB | 1,188 lines


File: make,  Node: Function Syntax,  Next: Text Functions,  Prev: Functions,  Up: Functions

Function Call Syntax
====================

A function call resembles a variable reference.  It looks like this:

     $(FUNCTION ARGUMENTS)

or like this:

     ${FUNCTION ARGUMENTS}

Here FUNCTION is a function name; one of a short list of names that are
part of `make'.  There is no provision for defining new functions.

The ARGUMENTS are the arguments of the function.  They are separated from
the function name by one or more spaces and/or tabs, and if there is more
than one argument they are separated by commas.  Such whitespace and commas
are not part of any argument's value.  Parentheses or braces, whichever you
use to surround the function call, can appear in an argument only in
matching pairs; the ones that were not used to surround the function call
can appear freely.  If the arguments contain other function calls or
variable references, it is wisest to surround them with the same delimiters
used for the containing function call.

The text written for each argument is processed by substitution of
variables and function calls in order to produce the argument value, which
is the text on which the function acts.

Commas and unmatched parentheses or braces cannot appear in the text of an
argument as written; leading spaces cannot appear in the text of the first
argument as written.  These characters can be put into the argument value
by variable substitution.  First define variables `comma' and `space' whose
values are isolated comma and space characters, then substitute those
variables where such characters are wanted, like this:

     comma:= ,
     space:= $(empty) $(empty)
     foo:= a b c
     bar:= $(subst $(space),$(comma),$(foo))
     # bar is now `a,b,c'.

 Here the `subst' function replaces each space with a comma, through the
value of `foo', and substitutes the result.


File: make,  Node: Text Functions,  Next: Foreach Function,  Prev: Function Syntax,  Up: Functions

Functions for String Substitution and Analysis
==============================================

Here are some functions that operate on substrings of a string:

`$(subst FROM,TO,TEXT)'
     Performs a textual replacement on the text TEXT: each occurrence of
     FROM is replaced by TO.  The result is substituted for the function
     call.  For example,

          $(subst ee,EE,feet on the street)

     substitutes the string `fEEt on the strEEt'.

`$(patsubst PATTERN,REPLACEMENT,TEXT)'
     Finds whitespace-separated words in TEXT that match PATTERN and
     replaces them with REPLACEMENT.  Here PATTERN may contain a `%' which
     acts as a wildcard, matching any number of any characters within a
     word.  If REPLACEMENT also contains a `%', the `%' is replaced by the
     text that matched the `%' in PATTERN.

     Whitespace between words is folded into single space characters;
     leading and trailing whitespace is discarded.

`$(strip STRING)'
     Removes leading and trailing whitespace from STRING and replaces each
     internal sequence of one or more whitespace characters with a single
     space.

`$(findstring FIND,IN)'
     Searches IN for an occurrence of FIND.  If it occurs, the value is
     FIND; otherwise, the value is empty.  You can use this function in a
     conditional to test for the presence of a specific substring in a
     given string.  *note Testing Flags::, for a practical application of
     `findstring'.

`$(filter PATTERN,TEXT)'
     Removes all whitespace-separated words in TEXT that do *not* match
     PATTERN, returning only matching words.  The pattern is one using `%'
     as used in the `patsubst' function.  This can be used to separate out
     different types of strings (such as filenames) in a variable.  For
     example:

          sources := foo.c bar.c ugh.h
          foo: $(sources)
                  cc $(filter %.c,$(sources)) -o foo

     says that `foo' depends of `foo.c', `bar.c' and `ugh.h' but only
     `foo.c' and `bar.c' should be specified in the command to the compiler.

`$(filter-out PATTERN,TEXT)'
     Removes all whitespace-separated words in TEXT that *do* match
     PATTERN, returning only matching words.  This is the exact opposite of
     the `filter' function.

`$(sort LIST)'
     Sorts the words of LIST in lexical order, removing duplicate words.
     The output is a list of words separated by single spaces.

Here is a realistic example of the use of `subst'.  Suppose that a makefile
uses the `VPATH' variable to specify a list of directories that `make'
should search for dependency files.  This example shows how to tell the C
compiler to search for header files in the same list of directories.

The value of `VPATH' is a list of directories separated by colons, such as
`src:../headers'.  First, the `subst' function is used to change the colons
to spaces:

     $(subst :, ,$(VPATH))

This produces `src ../headers'.  Then another function, `addprefix', can
turn each directory name into an `-I' flag.  These can be added to the
value of the variable `CFLAGS', which is passed automatically to the C
compiler, like this:

     override CFLAGS:= $(CFLAGS) $(addprefix -I,$(subst :, ,$(VPATH)))

The effect is to append the text `-Isrc -I../headers' to the previously
given value of `CFLAGS'.  The `override' directive is used so that the new
value is assigned even if the previous value of `CFLAGS' was specified with
a command argument (*Note Override Directive::.).

The function `strip' can be very useful when used in conjunction with
conditionals.  When comparing something with the null string `""' using
`ifeq' or `ifneq', you usually want a string of just whitespace to match
the null string.  Thus,

     .PHONY: all
     ifneq    "$(needs_made)" ""
     all: $(needs_made)
     else
     all:;@echo 'Nothing to make!'
     endif

might fail to have the desired results.  Replacing the variable reference
`"$(needs_made)"' with the function call `"$(strip $(needs_made))"' in the
`ifneq' directive would make it more robust.


File: make,  Node: Foreach Function,  Next: Filename Functions,  Prev: Text Functions,  Up: Functions

The `foreach' Function
======================

The `foreach' function is very different from other functions.  It causes
one piece of text to be used repeatedly, each time with a different
substitution performed on it.  It resembles the `for' command in the shell
`sh' and the `foreach' command in the C-shell `csh'.

The syntax of the `foreach' function is:

     $(foreach VAR,LIST,TEXT)

The first two arguments, VAR and LIST, are expanded before anything else is
done; note that the last argument, TEXT, is *not* expanded at the same
time.  Then for each word of the expanded value of LIST, the variable named
by the expanded value of VAR is set to that word, and TEXT is expanded.
Presumably TEXT contains references to that variable, so the expansions
will be different each time.

The result is that TEXT is expanded as many times as there are
whitespace-separated words in LIST.  The multiple expansions of TEXT are
concatenated, with spaces between them, to make the result of `foreach'.

This simple example sets the variable `files' to the list of all files in
the directories in the list `dirs':

     find_files = $(wildcard $(dir)/*)
     dirs := a b c d
     files := $(foreach dir,$(dirs),$(find_files))

For readability, it is a good idea to put the TEXT part of a `foreach'
function invokation into a variable.  Here we use the variable `find_file'
this way.  We make this a recursively-expanding variable by using `=' to
define it.  This is necessary so that when its value is substituted by
`foreach' the value is rescanned for variable references and function
calls.  This is what causes the `wildcard' function actually to be called.

This example has the same result (except for setting `find_files', `dirs'
and `dir') as the following example:

     files := $(wildcard a/* b/* c/* d/*)

The value of the variable VAR after the `foreach' function call is the same
as the value beforehand.  Other values taken from LIST are in effect only
temporarily, during the execution of `foreach'.  The variable VAR is a
simply-expanded variable during the execution of `foreach' but is returned
to the same flavor it was before the `foreach' when it is done.  *note
Flavors::.

If VAR was previously undefined, then it is defined as a recursively
expanded variable (`=', not `:=') during the `foreach' and remains so (with
a null value) afterward.

Because it is expanded before `foreach' runs, the VAR argument to `foreach'
need not be a literal variable name.  It can instead be a variable
expression resulting in the name.  Thus,

     dir := a
     var = $(whatsthevar)
     foo := dar
     whatsthevar := $(subst a,i,$(foo))
     files := $(foreach $(var),$(dirs),$(find_files))

is ultimately equivalent to the first example.  You must take care when
using complex variable expressions that result in variable names because
many strange things are legal variable names, and these might not be what
you intended.  For example,

     files := $(foreach Es escrito en espanol!,b c ch,$(find_files))

might be useful if `find_files' references the variable `Es escrito en
espanol!' (es un nombre bastante largo, no?), but it is more likely to be a
mistake.


File: make,  Node: Filename Functions,  Prev: Foreach Function,  Up: Functions

Functions for File Names
========================

Several of the built-in expansion functions relate specifically to taking
apart file names or lists of file names.

Each of these functions performs a specific transformation on a file name.
The argument of the function is regarded as a series of file names,
separated by whitespace.  (Leading and trailing whitespace is ignored.)
Each file name in the series is transformed in the same way and the results
are concatenated with single spaces between them.

`$(dir NAMES)'
     Extracts the directory-part of each file name in NAMES.  The
     directory-part of the file name is everything up through (and
     including) the last slash in it.  If the file name contains no slash,
     the directory part is the string `./'.  For example,

          $(dir src/foo.c hacks)

     produces the result `src/ ./'.

`$(notdir NAMES)'
     Extracts all but the directory-part of each file name in NAMES.  If
     the file name contains no slash, it is left unchanged.  Otherwise,
     everything through the last slash is removed from it.  A file name
     that ends with a slash becomes an empty string.  This is unfortunate,
     because it means that the result does not always have the same number
     of whitespace-separated file names as the argument had; but we do not
     see any other valid alternative.

     For example,

          $(notdir src/foo.c hacks)

     produces the result `foo.c hacks'.

`$(suffix NAMES)'
     Extracts the suffix of each file name in NAMES.  If the file name
     contains a period, the suffix is everything starting with the last
     period.  Otherwise, the suffix is the empty string.  This frequently
     means that the result will be empty when NAMES is not, and if NAMES
     contains multiple file names, the result may contain fewer file names.

     For example,

          $(suffix src/foo.c hacks)

     produces the result `.c'.

`$(basename NAMES)'
     Extracts all but the suffix of each file name in NAMES.  If the file
     name contains a period, the basename is everything starting up to (and
     not including) the last period.  Otherwise, the basename is the entire
     file name.  For example,

          $(basename src/foo.c hacks)

     produces the result `src/foo hacks'.

`$(addsuffix SUFFIX,NAMES)'
     The argument NAMES is regarded as a series of names, separated by
     whitespace; SUFFIX is used as a unit.  The value of SUFFIX is appended
     to the end of each individual name and the resulting larger names are
     concatenated with single spaces between them.  For example,

          $(addsuffix .c,foo bar)

     produces the result `foo.c bar.c'.

`$(addprefix PREFIX,NAMES)'
     The argument NAMES is regarded as a series of names, separated by
     whitespace; PREFIX is used as a unit.  The value of PREFIX is appended
     to the front of each individual name and the resulting larger names
     are concatenated with single spaces between them.  For example,

          $(addprefix src/,foo bar)

     produces the result `src/foo src/bar'.

`$(join LIST1,LIST2)'
     Concatenates the two arguments word by word: the two first words (one
     from each argument) concatenated form the first word of the result,
     the two second words form the second word of the result, and so on.
     So the Nth word of the result comes from the Nth word of each
     argument.  If one argument has more words that the other, the extra
     words are copied unchanged into the result.

     For example, `$(join a b,.c .o)' produces `a.c b.o'.

     Whitespace between the words in the lists is not preserved; it is
     replaced with a single space.

     This function can reverse the effect of the `dir' and `notdir'
     functions, after other processing has been done on the separated lists
     of directories and files.

`$(firstword NAMES)'
     The argument NAMES is regarded as a series of names, separated by
     whitespace.  The value is the first name in the series.  The rest of
     the names are ignored.  For example,

          $(firstword foo bar)

     produces the result `foo'.

`$(wildcard PATTERN)'
     The argument PATTERN is a file name pattern, typically containing
     wildcard characters.  The result of `wildcard' is a space-separated
     list of the names of existing files that match the pattern.

     Wildcards are expanded automatically in rules (*Note Wildcards::.).
     But they are not normally expanded when a variable is set, or inside
     the arguments of other functions.  Those occasions are when the
     `wildcard' function is useful.


File: make,  Node: Running,  Next: Implicit,  Prev: Functions,  Up: Top

How to Run `make'
*****************

A makefile that says how to recompile a program can be used in more than
one way.  The simplest use is to recompile every file that is out of date.
This is what `make' will do if run with no arguments.

But you might want to update only some of the files; you might want to use
a different compiler or different compiler options; you might want just to
find out which files are out of date without changing them.

By specifying arguments when you run `make', you can do any of these things
or many others.

* Menu:

* Makefile Arguments::    Arguments to specify which makefile to use.

* Goals::                 Goal arguments specify which parts of the makefile
                           should be used.

* Avoid Compilation::     How to avoid recompiling certain files.

* Instead of Execution::  Mode flags specify what kind of thing to do
                           with the commands in the makefile
                           other than simply execute them.

* Overriding::            Overriding a variable can specify an alternate
                           compiler, or alternate flags for the compiler,
                           or whatever else you program into the makefile.

* Testing::               How to proceed past some errors, to test compilation.

* Options::               Summary of all options `make' accepts.



File: make,  Node: Makefile Arguments,  Next: Goals,  Prev: Running,  Up: Running

Arguments to Specify the Makefile
=================================

The way to specify the name of the makefile is with the `-f' option.  For
example, `-f altmake' says to use the file `altmake' as the makefile.

If you use the `-f' flag several times (each time with a following
argument), all the specified files are used jointly as makefiles.

If you do not use the `-f' flag, the default is to use `./makefile', or, if
that does not exist, `./Makefile'.  *note Makefiles::.


File: make,  Node: Goals,  Next: Avoid Compilation,  Prev: Makefile Arguments,  Up: Running

Goals
=====

The "goals" are the targets that `make' should strive ultimately to update.
 Other targets are updated as well if they appear as dependencies of goals,
or dependencies of dependencies of goals, etc.

By default, the goal is the first target in the makefile (not counting
targets that start with a period or that appear in included makefiles).
Therefore, makefiles are usually written so that the first target is for
compiling the entire program or programs they describe.

You can specify a different goal or goal with arguments to `make'.  Use the
name of the goal as an argument.  If you specify several goals, `make'
processes each of them in turn, in the order you name them.

Any target in the makefile may be specified as a goal (unless it starts
with `-' or contains an `=').  Even targets not in the makefile may be
specified, if `make' can find implicit rules that say how to make them.

One use of specifying a goal is if you want to compile only a part of the
program, or only one of several programs.  Specify as a goal each file that
you wish to remake.  For example, consider a directory containing a several
programs, with a makefile that starts like this:

     .PHONY: all
     all: size nm ld ar as

If you are working on the program `size', you might want to say `make size'
so that only the files of that program are recompiled.

Another use of specifying a goal is to make files that aren't normally
made.  For example, there may be a file of debugging output, or a version
of the program that is compiled specially for testing, which has a rule in
the makefile but isn't a dependency of the default goal.

Another use of specifying a goal is to run the commands associated with a
phony target (*Note Phony Targets::.) or empty target (*Note Empty
Targets::.).  Many makefiles contain a phony target named `clean' which
deletes everything except source files.  Naturally, this is done only if
you request it explicitly with `make clean'.  Here is a list of typical
phony and empty target names:

`all'
     Make all the top-level targets the makefile knows about.

`clean'
     Delete all files that the makefile could remake.

`clobber'
     Delete absolutely everything the makefile could remake (whereas `make
     clean' often leaves intact some files that might take a long time to
     remake).

`install'
     Copy the executable file into a directory that users typically search
     for commands; copy any auxiliary files that the executable uses into
     the directories where it will look for them.

`print'
     Print listings of the source files that have changed.

`tar'
     Create a tar file of the source files.

`shar'
     Create a shell archive (shar file) of the source files.


File: make,  Node: Avoid Compilation,  Next: Instead of Execution,  Prev: Goals,  Up: Running

Avoiding Recompilation of Some Files
====================================

Sometimes you may have changed a source file but you don't want to
recompile all the files that depend on it.  For example, suppose you add a
macro or a declaration to a header file that many other files depend on.
Being conservative, `make' assumes that any change in the header file
requires recompilation of all dependent files, but you know that they don't
need to be recompiled and you would rather not waste the time waiting.

If you anticipate the problem before making the change, you can use the
`-t' flag.  This flag tells `make' not to run the commands in the rules,
but rather to mark the target up to date by changing its last-modification
date.  You would follow this procedure:

  1. Use the command `make' to recompile the source files that really need
     recompilation.

  2. Make the changes in the header files.

  3. Use the command `make -t' to mark all the object files as up to date.
     The next time you run `make', the changes in the header files will not
     cause any recompilation.

If you have already changed the header file at a time when some files do
need recompilation, it is too late to do this.  Instead, you can use the
`-o FILE' flag, which marks a specified file as ``old'' (*Note Options::.).
 This means that the file itself won't be remade, and nothing else will be
remade on its account.  Follow this procedure:

  1. Recompile the source files that need compilation for reasons independent
     of the particular header file, with `make -o HEADERFILE'.  If several
     header files are involved, use a separate `-o' option for each header
     file.

  2. Touch all the object files with `make -t'.


File: make,  Node: Instead of Execution,  Next: Overriding,  Prev: Avoid Compilation,  Up: Running

Instead of Executing the Commands
=================================

The makefile tells `make' how to tell whether a target is up to date, and
how to update each target.  But updating the targets is not always what you
want.  Certain options specify other activities for `make'.

`-t'
     ``Touch''.  The activity is to mark the targets as up to date without
     actually changing them.  In other words, `make' pretends to compile
     the targets but does not really change their contents.

`-n'
     ``No-op''.  The activity is to print what commands would be used to
     make the targets up to date, but not actually execute them.

`-q'
     ``Question''.  The activity is to find out silently whether the
     targets are up to date already; but execute no commands in either
     case.  In other words, neither compilation nor output will occur.

With the `-n' flag, `make' prints without execution the commands that it
would normally execute.

With the `-t' flag, `make' ignores the commands in the rules and uses (in
effect) the command `touch' for each target that needs to be remade.  The
`touch' command is also printed, unless `-s' or `.SILENT' is used.  For
speed, `make' does not actually invoke the program `touch'.  It does the
work directly.

With the `-q' flag, `make' prints nothing and executes no commands, but the
exit status code it returns is zero if and only if the targets to be
considered are already up to date.

It is an error to use more than one of these three flags in the same
invocation of `make'.

If you are not at all interested in what `make' *would* do, but rather in
some other information about `make', there are two options: the command
line `make -p -f /dev/null' will print the information in `make''s database
of variables, rules, directories and files and `make -v -f /dev/null' will
print information about what version of GNU `make' you are using.  *note
Options::.


File: make,  Node: Overriding,  Next: Testing,  Prev: Instead of Execution,  Up: Running

Overriding Variables
====================

You can override the value of a variable using an argument to `make' that
contains a `='.  The argument `V=X' (or `V:=X'; *Note Flavors::.) sets the
value of the variable V to X.

Values specified this way override all values specified in the makefile
itself; once you have set a variable with a command argument, any ordinary
attempt in the makefile to change that variable is simply ignored.

One way to use this facility is to pass extra flags to compilers.  For
example, in a properly written makefile, the variable `CFLAGS' is included
in each command that runs the C compiler, so a file `foo.c' would be
compiled like this:

     cc -c $(CFLAGS) foo.c

Thus, whatever value you set for `CFLAGS' affects each compilation that
occurs.  The makefile probably specifies the usual value for `CFLAGS', like
this:

     CFLAGS=-g

Each time you run `make', you can override this value and specify a
different value.  For example, if you say `make CFLAGS='-g -O'', each C
compilation will be done with `cc -c -g -O'.  (This illustrates how you can
enclose spaces and other special characters in the value of a variable when
you override it.)

The variable `CFLAGS' is only one of many standard variables that exist
just so that you can change them this way.  *note Implicit Variables::, for
a complete list.

You can also program the makefile to look at additional variables of your
own, giving the user ability to control other aspects of how the makefile
works by changing the variables.

There is one way that the makefile can change a variable that you have
overridden.  This is to use the `override' directive, which is a line that
looks like this: `override VARIABLE = VALUE'.  *note Override Directive::.


File: make,  Node: Testing,  Next: Options,  Prev: Overriding,  Up: Running

Testing the Compilation of a Program
====================================

Normally, when an error happens in executing a shell command, `make' gives
up immediately, returning a nonzero status.  No further commands are
executed for any target.  The error implies that the goal cannot be
correctly remade, and `make' reports this as soon as it knows.

When you are compiling a program that you have just changed, this is not
what you want.  Instead, you would rather that `make' try compiling every
file that can be tried, to show you all the compilation errors.

On these occasions, you should use the `-k' flag.  This tells `make' to
continue to consider the other dependencies of the pending targets,
remaking them if necessary, before it gives up and returns nonzero status.
For example, after an error in compiling one object file, `make -k' will
continue compiling other object files even though it already knows that
linking them will be impossible.  In addition to contuing after failing
shell commands, `make -k' will continue as much as possible after
discovering that it doesn't know how to make a target or dependency file.
This will always cause an error message, but without `-k', it is a fatal
error.  *note Options::.

The usual behavior of `make' assumes that your purpose is to get the goals
up to date; once `make' learns that this is impossible, it might as well
report the failure immediately.  The `-k' flag says that the real purpose
is to test as much as possible of the changes made in the program, perhaps
to find several independent problems so that you can correct them all
before the next attempt to compile.  This is why Emacs's `compile' command
passes the `-k' flag by default.


File: make,  Node: Options,  Prev: Testing,  Up: Running

Summary of Options
==================

Here is a table of all the options `make' understands:

`-b'
`-m'
     These options are ignored for compatibility with other versions of
     `make'.

`-c DIR'
     Change to directory DIR before executing the rules.  If multiple `-c'
     options are specified, each is interpreted relative to the previous
     one: `-c / -c etc' is equivalent to `-c /etc'.  This is typically used
     with recursive invocations of `make' (*Note Recursion::.).

`-d'
     Print debugging information in addition to normal processing.  The
     debugging information says which files are being considered for
     remaking, which file-times are being compared and with what results,
     which files actually need to be remade, which implicit rules are
     considered and which are applied---everything interesting about how
     `make' decides what to do.

`-f FILE'
     Use file FILE as a makefile.  *note Makefiles::.

`-i'
     Ignore all errors in commands executed to remake files.  *note Errors::.

`-I DIR'
     Specifies a directory DIR to search for included makefiles.  *note
     Include::.  If several `-I' options are used to specify several
     directories, the directories are searched in the order specified.

`-k'
     Continue as much as possible after an error.  While the target that
     failed, and those that depend on it, cannot be remade, the other
     dependencies of these targets can be processed all the same.  *note
     Testing::.

`-n'
     Print the commands that would be executed, but do not execute them.
     *note Instead of Execution::.

`-o FILE'
     Do not remake the file FILE even if it is older than its dependencies,
     and do not remake anything on account of changes in FILE.  Essentially
     the file is treated as very old and its rules are ignored.  *note
     Avoid Compilation::.

`-p'
     Print the data base (rules and variable values) that results from
     reading the makefiles; then execute as usual or as otherwise
     specified.  This also prints the version information given by the `-v'
     switch (see below).  To print the data base without trying to remake
     any files, use `make -p -f /dev/null'.

`-q'
     ``Question mode''.  Do not run any commands, or print anything; just
     return an exit status that is zero if the specified targets are
     already up to date, nonzero otherwise.  *note Instead of Execution::.

`-r'
     Eliminate use of the built-in implicit rules (*Note Implicit::.).
     Also clear out the default list of suffixes for suffix rules (*Note
     Suffix Rules::.).

`-s'
     Silent operation; do not print the commands as they are executed.
     *note Echoing::.

`-S'
     Cancel the effect of the `-k' option.  This is never necessary except
     in a recursive `make' where `-k' might be inherited from the top-level
     `make' via `MAKEFLAGS' (*Note Recursion::.) or if you set `-k' in
     `MAKEFLAGS' in your environment.

`-t'
     Touch files (mark them up to date without really changing them)
     instead of running their commands.  This is used to pretend (to fool
     future invocations of `make') that the commands were done.  *note
     Instead of Execution::.

`-v'
     Print the version of the `make' program plus a copyright, list of
     authors and notice of (non)warranty (short).  After this information
     is printed, processing continues normally.  To get the version
     information without doing anything else, use `make -v -f /dev/null'.

`-w'
     Print a message containing the working directory both before and after
     executing the makefile; this is useful for tracking down errors from
     builds of large directory trees.  *note Recursion::.


File: make,  Node: Implicit,  Next: Archives,  Prev: Running,  Up: Top

Using Implicit Rules
********************

Certain standard ways of remaking target files are used very often.  For
example, one customary way to make an object file is from a C source file
using the C compiler, `cc'.

"Implicit rules" tell `make' how to use customary techniques so that you
don't have to specify them in detail when you want to use them.  For
example, there is an implicit rule for C compilation.

Implicit rules work based on file names.  For example, C compilation
typically takes a `.c' file and makes a `.o' file.  So `make' applies the
implicit rule when it sees this combination of file-name endings.

A chain of implicit rules can apply in sequence; for example, `make' will
remake a `.o' file from a `.y' file by way of a `.c' file.

The built-in implicit rules use several variables in their commands so
that, by changing the values of the variables, you can change the way the
implicit rule works.  For example, the variable `CFLAGS' controls the flags
given to the C compiler by the implicit rule for C compilation.

You can define your own implicit rules by writing "pattern rules".

* Menu:

* Using Implicit::       How to use an existing implicit rule
                          to get the commands for updating a file.

* Catalogue of Rules::   Catalogue of built-in implicit rules.

* Implicit Variables::   By changing certain variables, you can
                          change what the predefined implicit rules do.

* Chained Rules::        Using a chain of implicit rules.

* Pattern Rules::        Defining new implicit rules.

* Search Algorithm::     Precise algorithm for applying implicit rules.



File: make,  Node: Using Implicit,  Next: Catalogue of Rules,  Prev: Implicit,  Up: Implicit

Using Implicit Rules
====================

To allow `make' to find a customary method for updating a target file, all
you have to do is refrain from specifying commands yourself.  Either write
a rule with no command lines, or don't write a rule at all.  Then `make'
will figure out which implicit rule to use based on which kind of source
file exists.

For example, suppose the makefile looks like this:

     foo : foo.o bar.o
             cc -o foo foo.o bar.o $(CFLAGS) $(LDFLAGS)

Because you mention `foo.o' but do not give a rule for it, `make' will
automatically look for an implicit rule that tells how to update it.  This
happens whether or not the file `foo.o' currently exists.

If an implicit rule is found, it supplies both commands and a dependency
(the source file).  You would want to write a rule for `foo.o' with no
command lines if you need to specify additional dependencies, such as
header files, that the implicit rule cannot supply.

Each implicit rule has a target pattern and dependency patterns.  There may
be many implicit rules with the same target pattern.  For example, numerous
rules make `.o' files: one, from a `.c' file with the C compiler; another,
from a `.p' file with the Pascal compiler; and so on.  The rule that
actually applies is the one whose dependency exists or can be made.

So, if you have a file `foo.c', `make' will run the C compiler; otherwise,
if you have a file `foo.p', `make' will run the Pascal compiler; and so on.

Of course, when you write the makefile, you know which implicit rule you
want `make' to use, and you know it will choose that one because you know
which other files are supposed to exist.  *note Catalogue of Rules::, for a
catalogue of all the predefined implicit rules.

Above, we said an implicit rule applies if the required dependency ``exists
or can be made''.  A file ``can be made'' if it is mentioned explicitly in
the makefile as a target or a dependency, or if an implicit rule can be
recursively found for how to make it.  When the implicit dependency is the
result of another implicit rule, we say that "chaining" is occurring.
*note Chained Rules::.

In general, `make' searches for an implicit rule for each target, and for
each double-colon rule, that has no commands.  A file that is mentioned
only as a dependency is considered a target whose rule specifies nothing,
so implicit rule search happens for it.  *note Search Algorithm::, for the
details of how the search is done.


File: make,  Node: Catalogue of Rules,  Next: Implicit Variables,  Prev: Using Implicit,  Up: Implicit

Catalogue of Implicit Rules
===========================

Here is a catalogue of predefined implicit rules which are always available
unless the makefile explicitly overrides or cancels them.  (*note Canceling
Rules::, for information on canceling or overriding an implicit rule.  The
`-r' option cancels all predefined rules.)

Compiling C programs
     `N.o' will be made automatically from `N.c'  with the command `$(CC)
     -c $(CFLAGS)'.

Compiling Pascal programs
     `N.o' will be made automatically from `N.p' with the command `$(PC) -c
     $(PFLAGS)'.

Compiling Fortran, EFL and Ratfor programs
     `N.o' will be made automatically from `N.e', `N.r', `N.F' or `N.f' by
     running the Fortran compiler.  The precise command used is as follows:

     `.e'
          `$(FC) -c $(EFLAGS)'.
     `.f'
          `$(FC) -c $(FFLAGS)'.
     `.F'
          `$(FC) -c $(FFLAGS)'.
     `.r'
          `$(FC) -c $(RFLAGS)'.

Preprocessing Fortran, EFL and Ratfor programs
     `N.f' will be made automatically from `N.e', `N.r' or `N.F'.  This
     rule runs just the preprocessor to convert a Ratfor, EFL or
     preprocessable Fortran program into a strict Fortran program.  The
     precise command used is as follows:

     `.e'
          `$(FC) -F $(EFLAGS)'.
     `.F'
          `$(FC) -F $(FFLAGS)'.
     `.r'
          `$(FC) -F $(RFLAGS)'.

Assembling assembler programs
     `N.o' will be made automatically from `N.s' by running the assembler
     `as'.  The precise command used is `$(AS) $(ASFLAGS)'.

Linking a single object file
     `N' will be made automatically from `N.o' by running the linker `ld'
     via the C compiler.  The precise command used is `$(CC) $(LDFLAGS) ...
     $(LOADLIBES)'.

     This rule does the right thing for a simple program with only one
     source file.  It will also do the right thing if there are multiple
     object files (presumably coming from various other source files), the
     first of which has a name matching that of the executable file.  Thus,

          x: y.o z.o

     when `x.c', `y.c' and `z.c' all exist will execute:

          cc -c x.c -o x.o
          cc -c y.c -o y.o
          cc -c z.c -o z.o
          cc x.o y.o z.o -o x
          rm -f x.o
          rm -f y.o
          rm -f z.o

     In more complicated cases, you must write an explicit command for
     linking.

Yacc for C programs
     `N.c' will be made automatically from `N.y' by running Yacc with the
     command `$(YACC) $(YFLAGS)'.

Yacc for Ratfor programs
     `N.r' will be made automatically from `N.yr' by running Yacc with the
     command `$(YACCR) $(YFLAGS)'.

Yacc for EFL programs
     `N.e' will be made automatically from `N.ye' by running Yacc with the
     command `$(YACCE) $(YFLAGS)'.

Lex for C programs
     `N.c' will be made automatically from `N.l' by by running Lex.  The
     actual command is `$(LEX) $(LFLAGS)'.

Lex for Ratfor programs
     `N.r' will be made automatically from `N.l' by by running Lex.  The
     actual command is `$(LEX) $(LFLAGS)'.

     The traditional custom of using the same suffix `.l' for all Lex files
     regardless of whether they produce C code or Ratfor code makes it
     impossible for `make' to determine automatically which of the two
     languages you are using in any particular case.  If `make' is called
     upon to remake an object file from a `.l' file, it must guess which
     compiler to use.  It will guess the C compiler, because that is more
     common.  If you are using Ratfor, make sure `make' knows this by
     mentioning `N.r' in the makefile.

RCS
     Any file `N' will be extracted if necessary from an RCS file named
     either `N,v' or `RCS/N,v'.  The precise command used is `$(CO)
     $(COFLAGS)'.  The variable `CO' has default value `co'.

SCCS
     Any file `N' will be extracted if necessary from an SCCS file named
     either `s.N' or `SCCS/s.N'.  The precise command used is `$(GET)
     $(GFLAGS)'.

     We recommend that you avoid the use of SCCS.  RCS is widely held to be
     superior, and is also free.  By choosing free software in place of
     comparable (or lesser) proprietary software, you support the free
     software movement.


File: make,  Node: Implicit Variables,  Next: Chained Rules,  Prev: Catalogue of Rules,  Up: Implicit

Variables Used by Implicit Rules
================================

The commands in built-in implicit rules make liberal use of certain
predefined variables.  You can redefine these variables, either in the
makefile or with arguments to `make', to alter how the implicit rules work
without actually redefining them.

For example, the command used to compile a C source file actually says
`$(CC) -c $(CFLAGS)'.  The default values of the variables used are `cc'
and nothing, resulting in the command `cc -c'.  By redefining `$(CC)' to
`ncc', you could cause `ncc' to be used for all C compilations performed by
the implicit rule.  By redefining `$(CFLAGS)' to be `-g', you could pass
the `-g' option to each compilation.  *All* implicit rules that do C
compilation use `$(CC)' to get the program name for the compiler and *all*
include `$(CFLAGS)' among the arguments given to the compiler.

The variables used in implicit rules fall into two classes: those that are
names of programs (like `CC') and those that contain arguments for the
programs (like `CFLAGS').  (The ``name of a program'' may also contain some
command arguments, but it must start with an actual executable program
name.)  If a variable value contains more than one argument, separate them
with spaces.

Here is a table of variables used as names of programs:

`AS'
     Program for doing assembly; default `as'.

`CC'
     Program for compiling C programs; default `cc'.

`CO'
     Program for extracting a file from RCS; default `co'.

`FC'
     Program for compiling or preprocessing Fortran, Ratfor, and EFL
     programs; default `f77'.

`GET'
     Program for extracting a file from SCCS; default `get'.

`LEX'
     Program to use to turn Lex grammars into C programs or Ratfor
     programs; default `lex'.

`PC'
     Program for compiling Pascal programs; default `pc'.

`YACC'
     Program to use to turn Yacc grammars into C programs; default `yacc'.

`YACCR'
     Program to use to turn Yacc grammars into Ratfor programs; default
     `yacc -r'.

`YACCE'
     Program to use to turn Yacc grammars into EFL programs; default `yacc
     -e'.

`RANLIB'
     Program to use to update the symbol-directory of an archive (the
     `__.SYMDEF' member); default `ranlib'.

Here is a table of variables whose values are additional arguments for the
programs above.  The default values for all of these is the empty string.

`ASFLAGS'
     Extra flags to give to the assembler (when explicitly invoked on a
     `.s' file).

`CFLAGS'
     Extra flags to give to the C compiler.

`EFLAGS'
     Extra flags to give to the Fortran compiler for EFL programs.

`FFLAGS'
     Extra flags to give to the Fortran compiler.

`LFLAGS'
     Extra flags to give to Lex.

`LDFLAGS'
     Extra flags to give to compilers when they are supposed to invoke the
     linker, `ld' (actually the value of the variable `LD').

`PFLAGS'
     Extra flags to give to the Pascal compiler.

`RFLAGS'
     Extra flags to give to the Fortran compiler for Ratfor programs.

`YFLAGS'
     Extra flags to give to Yacc.


File: make,  Node: Chained Rules,  Next: Pattern Rules,  Prev: Implicit Variables,  Up: Implicit

Chains of Implicit Rules
========================

Sometimes a file can be made by a sequence of implicit rules.  For example,
a file `N.o' could be made from `N.y' by running first Yacc and then `cc'.
Such a sequence is called a "chain".

If the file `N.c' exists, or is mentioned in the makefile, no special
searching is required: `make' finds that the object file can be made by C
compilation from `N.c'; later on, when considering how to make `N.c', the
rule for running Yacc will be used.  Ultimately both `N.c' and `N.o' are
updated.

However, even if `N.c' does not exist and is not mentioned, `make' knows
how to envision it as the missing link between `N.o' and `N.y'!  In this
case, `N.c' is called an "intermediate file".  Once `make' has decided to
use the intermediate file, it is entered in the data base as if it had been
mentioned in the makefile, along with the implicit rule that says how to
create it.

Intermediate files are remade using their rules just like all other files.
The difference is that the intermediate file is deleted when `make' is
finished.  Therefore, the intermediate file which did not exist before
`make' also does not exist after `make'.  The deletion is reported to you
by printing a `rm -f' command that shows what `make' is doing.  (You can
optionally define an implicit rule so as to preserve certain intermediate
files.  You can also list the target pattern of an implicit rule (such as
`%.o') as a dependency file of the special target `.PRECIOUS' to preserve
intermediate files whose target patterns match that file's name.)

A chain can involve more than two implicit rules.  For example, it is
possible to make a file `foo' from `RCS/foo.y,v' by running RCS, Yacc and
`cc'.  Then both `foo.y' and `foo.c' are intermediate files that are
deleted at the end.

No single implicit rule can appear more than once in a chain.  This means
that `make' will not even consider such a ridiculous thing as making `foo'
from `foo.o.o' by running the linker twice.  This constraint has the added
benefit of preventing any infinite loop in the search for an implicit rule
chain.

There are some special implicit rules to optimize certain cases that would
otherwise by handled by rule chains.  For example, making `foo' from
`foo.c' could be handled by compiling and linking with separate rules,
using `foo.o' as an intermediate file.  But what actually happens is that a
special rule for this case does the compilation and linking with a single
`cc' command.  The optimized rule is used in preference to the step-by-step
chain because it comes earlier in the ordering of rules.


File: make,  Node: Pattern Rules,  Next: Last Resort,  Prev: Chained Rules,  Up: Implicit

Defining and Redefining Pattern Rules
=====================================

You define an implicit rule by writing a "pattern rule".  A pattern rule
looks like an ordinary rule, except that its target contains the character
`%' (exactly one of them).  The target is considered a pattern for matching
file names; the `%' can match any substring, while other characters match
only themselves.

For example, `%.c' as a pattern matches any file name that ends in `.c'.
`s.%.c' as a pattern matches any file name that starts with `s.', ends in
`.c' and is at least five characters long.  (There must be at least one
character to match the `%'.)  The substring that the `%' matches is called
the "stem".

A pattern rule must have at least one dependency that uses `%'.  `%' in a
dependency of a pattern rule stands for the same stem that was matched by
the `%' in the target.  In order for the pattern rule to apply, its target
pattern must match the file name under consideration, and its dependency
patterns must name files that exist or can be made.  These files become
dependencies of the target.

There may also be dependencies that do not use `%'; such a dependency
attaches to every file made by this pattern rule.  These unvarying
dependencies are rarely useful.

The order in which pattern rules appear in the makefile is important
because the rules are considered in that order.  Of equally applicable
rules, the first one found is used.  The rules you write take precedence
over those that are built in.  Note, however, that a rule whose
dependencies actually exist or are mentioned always takes priority over a
rule with dependencies that must be made by chaining other implicit rules.

* Menu:

* Examples: Pattern Examples.  Real examples of pattern rule definitions.

* Vars: Automatic.             The automatic variables enable the commands
                                in pattern rules to act on the right files.

* Matching: Pattern Match.     Details of how patterns match.

* Match-Anything Rules::       Precautions in defining a rules that can
                                match any target file whatever.

* Canceling Rules::           Overriding or canceling built-in rules.

* Last Resort::                How to define a last-resort rule
                                that applies to any target that no other
                                rule applies to.

* Suffix Rules::               The old-fashioned way to define implicit rules.



File: make,  Node: Pattern Examples,  Next: Automatic,  Prev: Pattern Rules,  Up: Pattern Rules

Pattern Rule Examples
---------------------

Here are some examples of pattern rules actually predefined in `make'.
First, the rule that compiles `.c' files into `.o' files:

     %.o : %.c
             $(CC) -c $(CFLAGS) $< -o $@

defines a rule that can make any file `X.o' from `X.c'.  The command uses
the automatic variables `$@' and `$<' to substitute the names of the target
file and the source file as they are in each case where the rule apply
(*Note Automatic::.).

Here is a second built-in rule:

     % :: RCS/%,v
             $(CO) $(COFLAGS) $<

defines a rule that can make any file `X' whatever from a corresponding
file `X,v' in the subdirectory `RCS'.  Since the target is `%', this rule
will apply to any file whatever, provided the appropriate dependency file
exists.  The double colon makes the rule "terminal", which means that its
dependency may not be an intermediate file (*Note Match-Anything Rules::.).

